package ca.swank.hardquor;

/**
* Provides an interface for playing hardquor games. When developing
* a hardquor game:
* <UL>
*   <LI>create an implementation of this class. This may be a graphical user
*       interface, suitable for human players, or an artifically intelligent
*       machine which can generate legal moves when required.
*   <LI>the constructor for your implementation should take a
*       <CODE>hardquorGameClient</CODE> object as a parameter. This object
*       will handle all communication between the game and the hardquor game server.
*   <LI>communication occurs between the <CODE>hardquorGameClient</CODE> and the
*       <CODE>hardquorUserGame</CODE>. You will need to become comfortable with the
*       methods of <CODE>hardquorGameClient</CODE>, and call them when appropriate.
* </UL>
*
* @author Jesse Wilson
* @version 1.0 9/23/2001
*/
public interface hardquorUserGame
{
  public static final int ERROR_NONE = 0;
  public static final int ERROR_PLAYER_BLOCKED = 1;
  public static final int ERROR_INVALID_MOVE = 2;
  public static final int ERROR_NOT_ADJACENT = 3;
  public static final int ERROR_WRONG_PLAYER = 4;
  public static final int ERROR_OCCUPIED_TARGET = 5;
  public static final int ERROR_INSUFFICIENT_WALLS = 6;
  public static final int ERROR_GAME_COMPLETE = 7;
  public static final int ERROR_WALL_CRISSCROSS = 8;

  /**
  * a chat message received from the specified user. Chat messages should
  * be displayed to the game player in order for players to carry out a
  * conversation. Chat messages from the current user will also be notified
  * via this method. Note that chat messages received by this class are
  * in game messages, and distinct from out of game messages.
  *
  * @param user the username who created the message
  * @param message the text of the message
  */
  public void notifySpeak(String user, String message);

  /**
  * notification that a move required by the current player.
  */
  public void notifyTurn();

  /**
  * notification of the winner of the current game.
  *
  * @param winnerName the username of the game's winner.
  */
  public void notifyWinner(String winnerName);

  /**
  * a response to a move that has been made. An errorcode is notified
  * for correct and incorrect moves, with the integer providing error
  * type information. Errorcodes are constants of the
  * <CODE>hardquorUserGame</CODE> class.
  *
  * @param errorCode an integer indicating what type of error was made.
  */
  public void notifyError(int errorCode);

  /**
  * notification that a walk move has been made. If the implementation
  * keeps an copy of the board, the copy should be updated. For graphical
  * user interfaces, this should show a move action. Note that moves
  * made by the current player are only final when sent back to the
  * caller via this method; in effect, do not update internal copies of the board
  * from user moves; wait for this to be called to confirm.
  *
  * @param source a 2 integer array representing the initial coordinate of a player
  *        token. Index 0 is the x location, index 1 is the y location for all
  *        coordinates.
  * @param target a 2 integer array representing the new coordinate of a player
  *        token.
  */
  public void notifyMove(int[] source, int[] target);

  /**
  * notification that a wall move has been made. If the implementation
  * keeps an copy of the board, the copy should be updated. For graphical
  * user interfaces, this should show a move action. Note that moves
  * made by the current player are only final when sent back to the
  * caller via this method; in effect, do not update internal copies of the board
  * from user moves; wait for this to be called to confirm.
  *
  * @param a1 a 2 integer array representing the first of two cells on the A side of
  *        the new wall. This cell is no longer adjacent to <CODE>b1</CODE>.
  *        Index 0 is the x location, index 1 is the y location for all coordinates.
  * @param a2 a 2 integer array representing the second of two cells on the A side of
  *        the new wall. This cell is no longer adjacent to <CODE>b2</CODE>.
  * @param b1 a 2 integer array representing the first of two cells on the B side of
  *        the new wall. This cell is no longer adjacent to <CODE>a1</CODE>.
  * @param b2 a 2 integer array representing the second of two cells on the B side of
  *        the new wall. This cell is no longer adjacent to <CODE>a2</CODE>.
  */
  public void notifyMove(int[] a1, int[] a2, int[] b1, int[] b2);

  /**
  * notification that the specified user has quit the game. Note that his may occur
  * before a winner to the game has been found. Upon this method being called, no
  * subsequent moves will be accepted on this game.
  *
  * @param user the user quitting the current game.
  */
  public void notifyQuit(String user);

}